happy-dom

What is happy-dom?

happy-dom is a fast and lightweight DOM implementation for Node.js. It is designed to be compatible with the browser's DOM API, making it useful for server-side rendering, testing, and other scenarios where a DOM is needed outside of a browser environment.

What are happy-dom's main functionalities?

DOM Manipulation

happy-dom allows you to create and manipulate DOM elements just like you would in a browser environment. This is useful for server-side rendering and testing.

const { Window } = require('happy-dom');
const window = new Window();
const document = window.document;

const div = document.createElement('div');
div.textContent = 'Hello, World!';
document.body.appendChild(div);

console.log(document.body.innerHTML); // <div>Hello, World!</div>

Event Handling

happy-dom supports event handling, allowing you to add event listeners and dispatch events. This is useful for testing event-driven code.

const { Window } = require('happy-dom');
const window = new Window();
const document = window.document;

const button = document.createElement('button');
button.textContent = 'Click me';
button.addEventListener('click', () => {
  console.log('Button clicked!');
});
document.body.appendChild(button);

// Simulate a click event
const event = new window.Event('click');
button.dispatchEvent(event); // Button clicked!

Querying DOM Elements

happy-dom allows you to query DOM elements using methods like `querySelector` and `querySelectorAll`. This is useful for selecting and manipulating specific elements in the DOM.

const { Window } = require('happy-dom');
const window = new Window();
const document = window.document;

document.body.innerHTML = '<div class="test">Hello</div><div class="test">World</div>';
const elements = document.querySelectorAll('.test');

console.log(elements.length); // 2
console.log(elements[0].textContent); // Hello
console.log(elements[1].textContent); // World

Other packages similar to happy-dom

jsdom

jsdom is another popular DOM implementation for Node.js. It provides a more complete and detailed implementation of the DOM and other web standards. However, it is generally slower and more resource-intensive compared to happy-dom.

cheerio

cheerio is a fast, flexible, and lean implementation of core jQuery designed specifically for the server. It is not a full DOM implementation but provides a subset of jQuery functionality for parsing and manipulating HTML. It is faster and more lightweight than jsdom but less feature-rich.

linkedom

linkedom is a lightweight and fast DOM implementation for Node.js. It aims to be a minimalistic alternative to jsdom, providing essential DOM functionalities with better performance. It is similar to happy-dom in terms of performance and use cases.

README

About

Happy DOM is a JavaScript implementation of a web browser without its graphical user interface. It includes many web standards from WHATWG DOM and HTML.

The goal of Happy DOM is to emulate enough of a web browser to be useful for testing, scraping web sites and server-side rendering.

Happy DOM focuses heavily on performance and can be used as an alternative to JSDOM.

DOM Features

• Custom Elements (Web Components)

• Shadow Root (Shadow DOM)

• Declarative Shadow DOM

• Mutation Observer

• Tree Walker

• Fetch

And much more..

Works With

• Google LitHTML

• Google LitElement

• React

• Angular

• Vue

Installation

npm install happy-dom

Usage

Basic Usage

The example below will show you how to use Happy DOM.

import { Window } from 'happy-dom';

const window = new Window();
const document = window.document;

document.body.innerHTML = '<div class="container"></div>';

const container = document.querySelector('.container');
const button = document.createElement('button');

container.appendChild(button);

// Outputs "<div class="container"><button></button></div>"
console.log(document.body.innerHTML);

VM Context

The example below will show you how to setup a Node VM context to render a page in Happy DOM. The VM context can set the Happy DOM window object to be the global object and allow for JavaScript code to be executed scoped within the context.

import { Window } from 'happy-dom';
import VM from 'vm';

const window = VM.createContext(new Window());
const document = window.document;

window.location.href = 'http://localhost:8080';

document.write(`
    <html>
        <head>
             <title>Test page</title>
        </head>
        <body>
             <div class="container">
                  <!–– Content will be added here -->
             </div>
            <script>
                const element = document.createElement('div');
                const container = document.querySelector('.container');
                element.innerHTML = 'Test';
                container.appendChild(element);
            </script>
        </body>
    </html>
`);

// Will output "Test"
console.log(document.querySelector('.container div').innerHTML);

Server-Side Rendering of Web Components

The example below will show you how to setup a Node VM context to render a page with custom elements (web components) in Happy DOM. We can then use a new web feature called Declarative Shadow DOM to include the shadow roots in the HTML output.

Declarative Shadow DOM is only supported by Chromium based browsers. Unsupported browsers should safely fallback to being rendered using Javascript.

import { Window } from 'happy-dom';
import VM from 'vm';

const window = VM.createContext(new Window());
const document = window.document;

window.location.href = 'http://localhost:8080';

document.write(`
    <html>
        <head>
             <title>Test page</title>
        </head>
        <body>
            <div>
                <my-custom-element>
                    <span>Slotted content</span>
                </my-custom-element>
            </div>
            <script>
                class MyCustomElement extends HTMLElement {
                    constructor() {
                        super();
                        this.attachShadow({ mode: 'open' });
                    }

                    connectedCallback() {
                        this.shadowRoot.innerHTML = \`
                            <style>
                                :host {
                                    display: inline-block;
                                    background: red;
                                }
                            </style>
                            <div><slot></slot></div>
                        \`;
                    }
                }

                customElements.define('my-custom-element', MyCustomElement);
            </script>
        </body>
    </html>
`);

/*
Will output:
<my-custom-element>
    <span>Slotted content</span>
    <template shadowroot="open">
        <style>
            :host {
                display: inline-block;
                background: red;
            }
        </style>
        <div><slot></slot></div>
    </template>
</my-custom-element>
*/
console.log(document.body.querySelector('div').getInnerHTML({ includeShadowRoots: true }));

Additional Features

Happy DOM exposes two functions that may be useful when working with asynchrounous code.

whenAsyncComplete()

Returns a Promise that is resolved when all async tasks has been completed.

window.happyDOM.whenAsyncComplete().then(() => {
    // Do something when all async tasks are completed.
});

cancelAsync()

This method will cancel all running async tasks.

window.setTimeout(() => {
    // This timeout will be canceled
});
window.happyDOM.cancelAsync();

Performance

Operation	JSDOM	Happy DOM
Import / Require	333 ms	45 ms
Parse HTML	256 ms	26 ms
Serialize HTML	65 ms	8 ms
Render custom element	214 ms	19 ms
querySelectorAll('tagname')	4.9 ms	0.7 ms
querySelectorAll('.class')	6.4 ms	3.7 ms
querySelectorAll('[attribute]')	4.0 ms	1.7 ms
querySelectorAll('[class~="name"]')	5.5 ms	2.9 ms
querySelectorAll(':nth-child(2n+1)')	10.4 ms	3.8 ms

See how the test was done here

Jest

Happy DOM provide with a package called @happy-dom/jest-environment that makes it possible to use Happy DOM with Jest.

Global Registration

Happy DOM provide with a package called @happy-dom/global-registrator that can register Happy DOM globally. It makes it possible to use Happy DOM for testing in a Node environment.